The X-Philes (2nd Revision)/The X-Philes Number 1 (1995).iso/xphiles/hp95/freyja.exe/lha/FREYJA.DOC

Text File | 1992-04-13 | 19KB | 508 lines

            The Freyja Text Editor

           (Freyja Reduksjon Emacs, Ytre Jevn All)
         (Freyja Reduces Emacs Yet Joins All)
    (Norse goddess of sunshine, death, fertility, and divination)

         Copyright 1991,2 by Craig A. Finseth


Freyja is a text editor that implements the Emacs command set.  It is
not interactively extensible: to make changes, you must edit the
source code and recompile.

Freyja implements this author's favorite variation on the Emacs command
set.  As such, it is somewhat idiosyncratic.  However, if you don't
like something about it, you are welcome to change it.

While Freyja runs on UNIX systems, it was designed with MS/DOS systems
in mind.  In particular, it was designed to run on RAM-based laptop
and palmtop computers.

The Freyja documentation (including this file) is rather sketchy.  It
assumes that you know (1) what Emacs editors are all about (or at
least what text editors are all about) and (2) you aren't intimiated
by installing a C program (and figuring things out from source code).
(Well, MS/DOS users have it easy as executables are included.)
Books on emacs are listed with the Emacs implementations in the file
"emacs".

If you are intrigued by Emacs text editors, a list of other
implementations can be found in the "emacs" file included with this
distribution.  If you want to know more about how text editors work, I
will refer you to my book "The Craft of Text Editing"
(Springer-Verlag, 1991, ISBN 0-387-97616-7 or 3-540-97616-7).

The rest of this file and the "ftutoria.doc" file provide a basic
introduction to the Freyja editor and its commands.  In addition, the
files "fcmdlist.doc" and "fcmdxref.doc" provide a detailed command
list and command cross-reference chart.



EDITING MODEL

Freyja edits text in units of "buffers," where a buffer is a
one-dimensional array of bytes (characters).  Typically, a buffer is a
copy of a file being edited.

All editing operations are performed within (or between) buffers. Each
buffer has a "point."  The point is the location where all editing
changes take place.  The point is always between two characters.
Typically, the left edge of your display's cursor will be at the
point.

In addition, each buffer has a "mark."  This is a designated location
that is remembered for you.  You can move the point there (the ^X ^X
command) or move it to the point (the ^@ or ^[ SP commands).  (Also,
the ^Y, ^[ <, and ^[ > commands set the mark for you.)  The range of
characters between the point and the mark is called the "region" (it
doesn't matter which of the point and the mark is earlier in the
buffer).  Many commands operate over all text in the region.  For
example, you can delete ("cut") or copy this text.  You can also
convert it to uppercase, lowercase, indent it, outdent it, and so
forth.

Most deletion commands copy the deleted text to the "kill buffer."
This text can be retrieved with the ^Y command.  (The commands that do
not copy the text are ^D, ^H, ^? (UNIX), the whitespace-munging
commands, and the ^W command if given an argument.)  Successive
deletions accumulate text in the delete buffer. Hence, "^[ D ^[ D ^[
D" has the same effect as ^U 3 ^[ D".  Any non-accumulating deletion
command turns off the accumulation (it can be turned back on with the
^[ ^W command).  A "+" character appears in the mode line if
accumulating is on (i.e., the next deletion command will accumulate,
not replace, the kill buffer contents).



COMMAND TYPES

There are three types of commands:

- Regular commands are control characters.  They are written as ^#,
where "#" is some character.

- Control-X commands are typed by typing the ^X regular command, then
another character.  They are written as "^X #", where "#" can be any
character including control characters.  The upper/lower case of # is
ignored.

- Meta commands are typed by typing the ^[ regular command (use the
ESC or Escape key, if available), then another character.  They are
written as "^[ #", where "#" can be any character including control
characters.  The upper/lower case of # is ignored.



PARAMETERS

- You can give numeric arguments to commands by starting with the
universal argument (^U) regular command.  There are two forms:

    ^U ^U .... <cmd>    does <cmd> 4, 16, 64, 256, ... times
                depending upon the number of ^Us (each
                ^U is a multiplier by 4)
    ^U <integer> <cmd>    does <cmd> <integer> times

<cmd> can be any command.  Where it makes sense to do so, the argument
is used as a repeat count.

- Some commands prompt for string arguments.  If there is a default
value, it will be shown and can be selected by just typing ^M
(Return).  Otherwise, you can type your response.  Editing commands are:

    ^H, ^?    erase the last character
    ^G, ^[    cancel the command
    ^Y    yank the kill buffer into the prompt (be sure that the
        kill buffer text isn't too large, or you will have to
        listen to the bell for a while)

- Some commands prompt for single-character arguments.  They can be
cancelled with ^G or ^[.



HELP

The ^X H command gets you into the help subsystem.  This system allows
you to get help in many areas.  It include the "apropos" facility
which is a tradition among Emacs-type text editors.

This "apropos" command asks you for a word and lists those commands
that include that word in their descriptions.  For example, if you
entered "lines", it would list the commands that operate on lines.

You should keep the following synonyms in mind when using apropos:

    following | forward | next
    backward | preceding  | previous
    delete  | erase  | kill
    mark | region



DISPLAY

Most characters are displayed as themselves.  Three characters are
displayed specially:

- Tab characters (^I, 9 decimal) move the cursor to the next tab stop.
Tab stops are set every N characters, where N can be different for
each buffer.

- "Hard" newlines (^J, 10 decimal) move the cursor to the start of the
next line.

- "Soft" newlines (^_, 31 decimal) also move the cursor to the start
of the next line.  The difference between hard and soft newlines is
explained later.

An initialization parameter ("VISible grayspace," see the file
"freyja.ini") and command (^X `) control whether these characters and
spaces are "visible."  Try it and see.

Other control and meta characters (those with values < 31 decimal and
>= 127 decimal) are either displayed in "caret" notation or as
themselves (controlled with the "USE caret notation" initialization
parameter).

Freyja supports two separate windows.  You create two windows by
giving the ^X 2 or ^X 3 command (they only differ in which window the
cursor is left in). While these windows initially display the same
text, you can move each independantly of the other.  You can switch
windows by giving the ^X O command.  You can grow the current window
by giving the ^X ^ command. (No window can be less than 3 lines
high.)  You can return to one window by giving the ^X 1 command.

Each window can be separately scrolled vertically or horizontally.
(Long lines do not wrap.)  Use the ^X < and ^X > commands to scroll
the window.  Note that the window will always be moved to show the
point.



THE STATUS LINE

The last line on the screen is called the status line.  It shows the
name and version number of the editor, the name of the file currently
being edited, the percentage through the buffer that the point is, and
two other indicators:

- A "*" is displayed if the buffer has been modified since it was
last read from or written to the associated file.

- A "+" is displayed if the next deletion command will add to instead
of replacing the contents of the kill buffer.



FILE AND BUFFER COMMANDS

Freyja allows you to edit or view up to 11 files at once.  Freyja
commands work on a copy of the file, not the file itself.  Each of
these copies is called a buffer.  There are a number of commands that
transfer the text between the buffer and the file.

The ^X ^F (find file) command asks for the name of a file.  If the
file is already present in a buffer, it switches to that buffer.  If
not, it creates a new buffer and reads the file in.  You can create a
new file by doing a ^X ^F and giving the name of the new (presumably
non-existant) file.

The ^X ^R (read file) command asks for the name of a file and reads
it on top of the file in the current buffer.  It is most often used
for refreshing a modified buffer from the file itself.

The ^X ^S (save file) command save the contents of the buffer in the
file.

The ^X ^W (write file) command asks for the name of a file and saves
the buffer to that file.

You can also move among the buffers.  These buffers are arranged in a
ring, and you can give the commands:

    ^X B    move to the next buffer in the ring
    ^X V    move to the previous buffer in the ring
    ^X K    delete the current buffer and move to the previous
        buffer in the ring



SEARCHING

When searching, you are prompted for the entire string and that string
is then searched for as a unit.  If the search is not successful, the
point does not move.  A lower-case character in the search string will
match either a lower- or upper-case character in the buffer.  An
upper-case character in the search string will only match an
upper-case charecter in the buffer.  Thus, a search string of "the"
matches "the" or "The", but a search string of "ROM" does not match
"from".



REPLACE AND QUERY REPLACE

The ^[ R (replace) and ^[ ^R (query replace) commands let you
substitute one string for another.  The commands ask for an old
string and a new one.  They search for each occurrance of the old
string in the same manner as ^S starting with the point and
proceeding to the end of the buffer.  The replace command simply
replaces the old string with the new.  The query replace command asks
you at each occurrance.  You can type:

    Y,y,space    do the replace and continue
    N,n,^H,^?    DON'T do the replace and continue
    ,        do the replace, show the results, and ask for
            Y/N confirmation
    .        do the replace and don't continue
    !        do the replace and all rest without asking
            (i.e. turn into a replace command)
    ^G,^[        exit immediately



WORD WRAP (SOFT vs. HARD NEWLINES)

Frey supports three types of filling / wrapping.

The first type is "none:" no wrapping is done automatically.
Paragraphs can be refilled with the ^[ Q command.

The second type is "hard:" filling is done as input is typed.
However, only the current line is filled.  Paragraphs can be refilled
with the ^[ Q command.  Hard newlines are used.  Thus, when the file
is written to disk, an actual newline (^J or ^M/^J) will be in the
file.  Paragraphs are in general separated by two consecutive
newlines.  Freyja's paragraph commands will in addition treat newline
/ space, newline / Tab, newline / ".", and newline / "@" as paragraph
breaks.

The third type is "wrap:" the current paragraph is refilled as input
is typed.  Paragraphs can be refilled with the ^[ Q command.  Lines
within paragraphs are separated by soft newlines (^_, 31 decimal).  A
hard newline ends a paragraph.

Regions can be converted between hard and soft newlines with the ^X {
and ^X } commands.

You can control the word wrap mode on a buffer with the ^X / command.

If the initialization parameter "WRAp allowed" is "yes," each file
will be checked for a "ruler line" as it is being read in.  If the
ruler line is present, it is used to set the per-buffer settings
(margins, tab spacing, and wrap mode).

The ruler line is compatible with that used by Borland's Sprint(tm)
package and has the following format:

    ^KR #,T #,L #?

where:

    ^K is the vertical tab control character, 11 decimal
    R # sets the right margin to column #
    T # sets the tab spacing to # columns
    L # sets the left margin to column #
    ?, if present, sets the wrap mode (if not present, word wrap
        is assumed).  ? can be:

        ,N    none
        ,F    hard fill
        ,W    word wrap

The ruler line must be on a line by itself (no leading or trailing
text) and must be the first line in the file that is neither blank nor
starts with a "." or "@" character.  A single, leading, blank line, if
present, is skipped.  Thus, if your file starts with, say:

    <blank>
    @PageFooting()
    <ruler>

The ruler line will be found.



SYSTEM BUFFERS

A buffer whose name starts with a percent sign ("%") is a "system
buffer."  These buffers are created, overwritten, and otherwise
manipulated by Freyja without notice.  They are otherwise ordinary
buffers.

The buffer commands (^X ^B, ^X B, ^X K, ^X V) ordinarily skip these
buffers.  You can cause the commands to not skip these buffers by
supplying an argument to the command.

When you exit Freyja, the modification flags of system buffers are NOT
CHECKED: if you have made significant changes to any of these buffers,
the changes will be lost unless you save them before giving an exit
command.

Partial list of system buffers:

    %bufflist%    the list of buffers is placed here (^X ^B)
    %cal%        calendar output
    %calc%        used for information transfer to/from the calculator
    %dired%        the output of dired (^X ^D)
    %help%        help command responses (^X H)
    %kill%        the kill buffer: DON'T DELETE THIS!!!
            (actually, you can't)
    %scratch%    this buffer is created whenver you don't have
            any non-system buffers



FILE LOADING

When Freyja loads a pre-defined file (e.g., "freyja.ini" or any of the
"f*.doc" files), it looks in these places in this order:

    if present, the directory indicated by the "FREYJADIR"
        environment variable
    if present, the directory indicated by the "HOME"
        environment variable
    the search path ("PATH")
    the current directory



INITIALIZATION FILE

Freyja's operation can be tailored in various ways.  These parameters
are set in the "freyja.ini" file.  The specific parameters are
documented in there.  For the most part, the only way to change a
parameter is to change the file, then exit and restart Freyja.



COMMAND LINE OPTIONS

Freyja is started with the following command line:

    freyja [-options] [file(s)]

where the following options are supported:

    -z #    Sets the swap size to # Kbytes for this invocation only.

    -s X    Sets the screen type to X for this invocation only.
        See "freyja.ini" for legal values.

The upper/lower case of options is ignored.  Options can be given in
any order and intermixed with file names.

"File(s)" is a list of zero or more file names.  Each one is read in
with the equivalent of a ^X ^F command.  If none are supplied, you are
left in the system buffer "%scratch%".



ALTERNATE KEYBOARD (MSDOS)

Freyja can be used with external keyboards in two different ways.

First, you can set Freyja to use a VT100 screen, set the keyboard to
Console, and then use the MS/DOS CTTY command to change where your
input is coming from.  This allows you to use Freyja from an external
terminal (or computer running terminal emulator software).  The
FREYJA.INI file would look like this:

    scr v
    scs j    # HP95LX Jaguar only
    key c

Second, you can set Freyja to use the computer's screen but fetch
keyboard input from the serial port.  This would be useful if you have
an external keyboard.  The FREYJA.INI file would look like this:

    scr m
    scs j    # HP95LX Jaguar only
    key s

In both cases you set the port to use, its speed, and its character
format with the MS/DOS MODE command.  (I find that the HP95LX powers
up in 9600 bps, 8 bits, no parity.)

Note that you cannot use the "special J" setting in FREYJA.INI, as
this setting causes Freyja to override any screen or keyboard
settings.


USE WITH THE HP95LX (JAGUAR, MSDOS)

Special type 'J' is for the HP95LX.  If special type 'J' is used, the
following changes are made to program Execution:

- The screen type is forced to memory-mapped.
- Only a 16 x 40 screen is used.
- HP-specific ROM BIOS calls are used for keyboard input.
- If the PA1 P option is supplied in the FREYJA.INI file and the
keyboard type is not C or S, the serial port is turned off during
operation and on at exit.
- Several function keys (the blue keys) > 132 are remapped.
- The MENU key works.
- The Blue keys cause Freyja to exit, then invoke the specified
application.  (They push a space and the function key for the
application onto the keyboard buffer.)
- The cursor is set to a block cursor.
- The SETUP number format is imported into the calculator.
- The SETUP starting day-of-the-week is imported into the calendar.
- The CHAR function keys work.
- The search path for the help files automatically includes C:\_DAT.
It is not included for FREYJA.INI, as that file must be loaded before
it can read the special handling parameter...



DIFFERENCES IN THE SYSTEM MANAGER COMPLIANT VERSION (JAGUAR, MSDOS)

- You can tell that you are running the system-manager compliant version
because the menu has options for using the clipboard.

- The screen type is forced to memory-mapped.
- Only a 16 x 40 screen is used.
- Application manager calls are used for keyboard input.
- Any SCR, SCS, KEY, SPE, and PA1 directives in "freyja.ini" are ignored.
- The calculator is not present (the Turbo C floating point libraries
use and interrupt in their interface; such use conflicts with sytem
manage compliance guidelines)
- The execute system command function is not present.
- The SETUP starting day-of-the-week is imported into the calendar.
- The serial port power is *not affected.*
- The MENU key works.
- The File menu is used.
- The clipboard is accessible via the menu.
- The cursor is set to a block cursor.
- The CHAR function keys work.
- The search path for FREYJA.INI and the help files is forced to
be C:\_DAT and the current directory.

               >>> Important Note <<<

LOTUS grabs all available memory when it starts up.  Freyja needs
memory for the swap space.  If you start Freyja, then LOTUS,
everything works fine.  It doesn't work if you start LOTUS first.



FUTURE DIRECTIONS

It would be nice to see support for:

- Left margin support is really awful.  Since I never use it...
- More than two windows.
- Incremental search.
- Support a kill ring.
- Full DIRED.
- Full buffer edit mode.
- File name completion.
- Set the current directory on a per-buffer basis.
- Allow full editing on prompts.
- Enhance the calculator to include, say, all features from the
HP-16C, HP-19BII, HP-41CX, and HP-48SX.
- .XIP (Jaguar-specific)